package com.googlecode.dgwt.client.dojo.data.listener;


/**
 * Represents a listener that will update the data to the user on screen when it
 * changes.
 * 
 * @author wellsantos@wellsantos.com
 * @since 0.01
 */
public interface DataListener<Item> extends FetchListener<Item> {

    /**
     * {@inheritDoc}<br/>
     * So, data should be updated.
     */
    public void onAdd(int index, Item item);
    
    /**
     * {@inheritDoc}<br/>
     * So, data should be updated.
     */
    public void onRemove(int index, Item item);
    
    /**
     * {@inheritDoc}<br/>
     * So, data should be updated.
     */
    public void onReplace(int index, Item oldItem, Item newItem);

    /**
     * {@inheritDoc}<br/>
     * Only in this case, do <b>not</b> update data. <br/>
     * Maybe, only a column of the item has been changed. So, you must wait for
     * a subsequent call of one of the refresh methods: <br/>
     * <ul>
     * <li> {@link #onRefreshValue(Object, int)}</li>
     * <li> {@link #onRefreshItem(Object)}</li>
     * <li> {@link #onRefresh()}</li>
     * </ul>
     */
    public void onModified(Item item);

    /**
     * Event fired when all items in the store should be updated.
     */
    public void onRefresh();
    
    /**
     * Event fired when only an item should be updated.
     * 
     * @param item the item
     */
    public void onRefreshItem(Item item);

    /**
     * Event fired just when a value of an item should be updated.
     * 
     * @param item
     *            the item
     * @param columnIndex
     *            the column index of the value changed
     */
    public void onRefreshValue(Item item, int columnIndex);
    
}
